﻿<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
  
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <title>Links and Cross References | DocFX website </title>
    <meta name="viewport" content="width=device-width">
    <meta name="title" content="Links and Cross References | DocFX website ">
    <meta name="generator" content="docfx 2.37.0.0">
    
    <link rel="shortcut icon" href="../favicon.ico">
    <link rel="stylesheet" href="../styles/docfx.vendor.css">
    <link rel="stylesheet" href="../styles/docfx.css">
    <link rel="stylesheet" href="../styles/main.css">
    <meta property="docfx:navrel" content="../toc.html">
    <meta property="docfx:tocrel" content="toc.html">
    
    <meta property="docfx:rel" content="../">
    
  </head>
  <body data-spy="scroll" data-target="#affix" data-offset="120">
    <div id="wrapper">
      <header>
        
        <nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
          <div class="container">
            <div class="navbar-header">
              <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
                <span class="sr-only">Toggle navigation</span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
              </button>
              
              <a class="navbar-brand" href="../index.html">
                <img id="logo" class="svg" src="../logo.svg" alt="">
              </a>
            </div>
            <div class="collapse navbar-collapse" id="navbar">
              <form class="navbar-form navbar-right" role="search" id="search">
                <div class="form-group">
                  <input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
                </div>
              </form>
            </div>
          </div>
        </nav>
        
        <div class="subnav navbar navbar-default">
          <div class="container hide-when-search" id="breadcrumb">
            <ul class="breadcrumb">
              <li></li>
            </ul>
          </div>
        </div>
      </header>
      <div class="container body-content">
        
        <div id="search-results">
          <div class="search-list"></div>
          <div class="sr-items">
            <p><i class="glyphicon glyphicon-refresh index-loading"></i></p>
          </div>
          <ul id="pagination"></ul>
        </div>
      </div>
      <div role="main" class="container body-content hide-when-search">
        
        <div class="sidenav hide-when-search">
          <a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
          <div class="sidetoggle collapse" id="sidetoggle">
            <div id="sidetoc"></div>
          </div>
        </div>
        <div class="article row grid-right">
          <div class="col-md-10">
            <article class="content wrap" id="_content" data-uid="">
<h1 id="links-and-cross-references">Links and Cross References</h1>

<p>Markdown provides a <a href="https://daringfireball.net/projects/markdown/syntax#link">syntax</a> to create hyperlinks.
For example, the following syntax:</p>
<pre><code class="lang-markdown">[bing](http://www.bing.com)
</code></pre>
<p>Will render to:</p>
<pre><code class="lang-html">&lt;a href=&quot;http://www.bing.com&quot;&gt;bing&lt;/a&gt;
</code></pre>
<p>Here the url in the link could be either absolute url pointing to another website (<code>www.bing.com</code> in the above example),
or a relative url pointing to a local resource on the same server (for example, <code>about.html</code>).</p>
<p>When working with large documentation project that contains multiple files, it is often needed to link to another Markdown file using the relative path in the source directory.
Markdown spec doesn't have a clear definition of how this should be supported.
What's more, there is also a common need to link to another file using a &quot;semantic&quot; name instead of its file path.
This is especially common in API reference docs, for example, you may want to use <code>System.String</code> to link to the topic of <code>String</code> class, without knowing it's actually located in <code>api/system/string.html</code>, which is auto generated.</p>
<p>In this document, you'll learn the functionalities DocFX provides for resolving file links and cross reference, which will help you to reference other files in an efficient way.</p>
<h2 id="link-to-a-file-using-relative-path">Link to a file using relative path</h2>
<p>In DocFX, you can link to a file using its relative path in the source directory. For example,</p>
<p>You have a <code>file1.md</code> under root and a <code>file2.md</code> under <code>subfolder/</code>:</p>
<pre><code>/
|- subfolder/
|  \- file2.md
\- file1.md
</code></pre>
<p>You can use relative path to reference <code>file2.md</code> in <code>file1.md</code>:</p>
<pre><code class="lang-markdown">[file2](subfolder/file2.md)
</code></pre>
<p>DocFX converts it to a relative path in output folder structure:</p>
<pre><code class="lang-html">&lt;a href=&quot;subfolder/file2.html&quot;&gt;file2&lt;/a&gt;
</code></pre>
<p>You can see the source file name (<code>.md</code>) is replaced with output file name (<code>.html</code>).</p>
<div class="NOTE">
<h5>Note</h5>
<p>DocFX does not simply replace the file extension here (<code>.md</code> to <code>.html</code>), it also tracks the mapping between input and
output files to make sure source file path will resolve to correct output path. For example, if in the above case,
<code>subfolder</code> is renamed to <code>subfolder2</code> using <a href="docfx.exe_user_manual.html#4-supported-file-mapping-format">file mapping</a> in
<code>docfx.json</code>, in output html, the link url will also resolve to <code>subfolder2/file2.html</code>.</p>
</div>
<h3 id="relative-path-vs-absolute-path">Relative path vs. absolute path</h3>
<p>It's recommended to always use relative path to reference another file in the same project. Relative path will be resolved during build and produce build warning if the target file does not exist.</p>
<div class="TIP">
<h5>Tip</h5>
<p>File must be included in <code>docfx.json</code> to be processed by DocFX, so if you see a build warning about broken link but the file
actually exists in your file system, go and check whether this file is included in <code>docfx.json</code>.</p>
</div>
<p>You can also use absolute path (path starts with <code>/</code>) to link to another file, but DocFX won't check its correctness for you and will keep it as-is in the output HTML.
That means you should use the output file path as absolute path. For example, in the above case, you can also write the link as follows:</p>
<pre><code class="lang-markdown">[file2](/subfolder/file2.html)
</code></pre>
<p>Sometimes you may find it's complicated to calculate relative path between two files.
DocFX also supports path starts with <code>~</code> to represent path relative to the root directory of your project (i.e. where <code>docfx.json</code> is located).
This kind of path will also be validated and resolved during build. For example, in the above case, you can write the following links in <code>file2.md</code>:</p>
<pre><code class="lang-markdown">[file1](~/file1.md)

[file1](../file1.md)
</code></pre>
<p>Both will resolve to <code>../file1.html</code> in output html.</p>
<div class="WARNING">
<h5>Warning</h5>
<p><a href="https://daringfireball.net/projects/markdown/syntax#autolink">Automatic link</a> doesn't support relative path.
If you write something like <code>&lt;file.md&gt;</code>, it will be treated as an HTML tag rather than a link.</p>
</div>
<h3 id="links-in-file-includes">Links in file includes</h3>
<p>If you use <a href="../spec/docfx_flavored_markdown.html#file-inclusion">file include</a> to include another file, the links in included file is relative to the included file. For example, if <code>file1.md</code> includes <code>file2.md</code>:</p>
<pre><code class="lang-markdown">[!include[file2](subfolder/file2.md)]
</code></pre>
<p>All links in <code>file2.md</code> are relative to the <code>file2.md</code> itself, even when it's included by <code>file1.md</code>.</p>
<div class="NOTE">
<h5>Note</h5>
<p>Please note that the file path in include syntax is handled differently than Markdown link.
You can only use relative path to specify location of the included file.
And DocFX doesn't require included file to be included in <code>docfx.json</code>.</p>
</div>
<div class="TIP">
<h5>Tip</h5>
<p>Each file in <code>docfx.json</code> will build into an output file. But included files usually don't need to build into individual
topics. So it's not recommended to include them in <code>docfx.json</code>.</p>
</div>
<h3 id="links-in-inline-html">Links in inline HTML</h3>
<p>Markdown supports <a href="https://daringfireball.net/projects/markdown/syntax#html">inline HTML</a>. DocFX also supports to use relative path in inline HTML. Path in HTML link (<code>&lt;a&gt;</code>), image (<code>&lt;img&gt;</code>), script (<code>&lt;script&gt;</code>) and css (<code>&lt;link&gt;</code>) will also be resolved if they're relative path.</p>
<h2 id="using-cross-reference">Using cross reference</h2>
<p>Besides using file path to link to another file, DocFX also allows you to give a file a unique identifier so that you can reference this file using that identifier instead of its file path. This is useful in the following cases:</p>
<ol>
<li>Path to file is long and difficult to memorize or changes frequently.</li>
<li>API reference documentation is usually auto generated so it's difficult to find its file path.</li>
<li>You want to reference to files in another project without need to know its file structure.</li>
</ol>
<p>The basic syntax for cross referencing a file is:</p>
<pre><code class="lang-markdown">&lt;xref:id_of_another_file&gt;
</code></pre>
<p>This is similar to <a href="https://daringfireball.net/projects/markdown/syntax#autolink">automatic link</a> syntax in Markdown but with a <code>xref</code> scheme. This link will build into:</p>
<pre><code class="lang-html">&lt;a href=&quot;path_of_another_file&quot;&gt;title_of_another_file&lt;/a&gt;
</code></pre>
<p>As you can see, one benefit of using cross reference is that you don't need to specify the link text and DocFX will automatically resolve it for you.</p>
<div class="NOTE">
<h5>Note</h5>
<p>Title is extracted from the first heading of the Markdown file. Or you can also specify title using title metadata.</p>
</div>
<h3 id="define-uid">Define UID</h3>
<p>The unique identifier of a file is called UID (stands for unique identifier) in DocFX. For Markdown file, you can specify its UID by adding a UID metadata in <a href="../spec/docfx_flavored_markdown.html#yaml-header">YAML header</a>. For example, the following Markdown defined a UID &quot;fileA&quot;.</p>
<pre><code class="lang-markdown">---
uid: fileA
---

# This is fileA
...
</code></pre>
<div class="NOTE">
<h5>Note</h5>
<p>UID is supposed to be unique inside a project. If you define duplicate UID for two files, the resolve result is undetermined.</p>
</div>
<p>For API reference files, UID is auto generated by mangling API's signature. For example, System.String class's UID is <code>System.String</code>. You can open the generated YAML files to lookup the value of UID.</p>
<div class="NOTE">
<h5>Note</h5>
<p>Conceptual Markdown file doesn't have UID generated by default. So it cannot be cross referenced unless you give it a UID.</p>
</div>
<h3 id="different-syntax-of-cross-reference">Different syntax of cross reference</h3>
<p>Besides the auto link, we also support some other ways to use cross references:</p>
<h4 id="markdown-link">Markdown link</h4>
<p>In Markdown link, you can also use <code>xref</code> in link url:</p>
<pre><code class="lang-markdown">[link_text](xref:uid_of_another_file)
</code></pre>
<p>This will resolve to:</p>
<pre><code class="lang-html">&lt;a href=&quot;path_of_another_file&quot;&gt;link_text&lt;/a&gt;
</code></pre>
<p>In this case, we won't resolve the link text for you because you already specified it, unless the <code>link_text</code> is empty.</p>
<h4 id="shorthand-form">Shorthand form</h4>
<p>You can also use <code>@uid_to_another_file</code> to quickly reference another file. There are some rules for DocFX to determine whether a string following <code>@</code> are UID:</p>
<ol>
<li><p>The string after <code>@</code> must start with <code>[A-Za-z]</code>, and end with:</p>
<ul>
<li>Whitespace or line end</li>
<li>Punctuation (<code>[.,;:!?`~]</code>) followed by whitespace or line end</li>
<li>Two or more punctuations (<code>[.,;:!?`~]</code>)</li>
</ul>
</li>
<li><p>A string enclosed by a pair of quotes (<code>'</code> or <code>&quot;</code>)</p>
</li>
</ol>
<p>The render result of <code>@</code> form is same as auto link form. For example, <code>@System.String</code> is same as <code>&lt;xref:System.String&gt;</code>.</p>
<div class="WARNING">
<h5>Warning</h5>
<p>Since <code>@</code> is a common character in a document, DocFX doesn't show a warning if UID isn't found for a shorthand form xref link.
Warnings for missing links are shown for auto links and Markdown links.</p>
</div>
<h4 id="using-hashtag-in-cross-reference">Using hashtag in cross reference</h4>
<p>Sometimes you need to link to the middle of a file (an anchor) rather than jump to the beginning of a file. DocFX also allows you to do that.</p>
<p>In Markdown link or auto link, you can add a hashtag (<code>#</code>) followed by the anchor name after UID. For example:</p>
<pre><code class="lang-markdown">&lt;xref:uid_to_file#anchor_name&gt;

[link_text](xref:uid_to_file#anchor_name)

@uid_to_file#anchor_name
</code></pre>
<p>Will all resolve to <code>url_to_file#anchor_name</code> in output HTML.</p>
<p>The link text still resolves to the title of the whole file. If it's not what you need, you can specify your own link text.</p>
<div class="NOTE">
<h5>Note</h5>
<p>Hashtag in <code>xref</code> is always treated as separator between file name and anchor name. That means if you have <code>#</code> in UID, it has
to be <a href="https://en.wikipedia.org/wiki/Percent-encoding">encoded</a> to <code>%23</code>.</p>
<p>Actually <code>xref</code> format follows URI standard so all <a href="https://tools.ietf.org/html/rfc3986#section-2.2">reserved characters</a> should be encoded.</p>
</div>
<h3 id="link-to-overwrite-files">Link to overwrite files</h3>
<p><a href="intro_overwrite_files.html">Overwrite file</a> itself doesn't build into individual output file. It's merged with the API reference item model to build into a single file. If you want to link to the content inside an overwrite file (for example, an anchor), you cannot use the path to the overwrite file. Instead, you should either cross reference its UID, or link to the YAML file that contains the API.</p>
<p>For example, you have String class which is generated from <code>system.string.yml</code>, then you have a <code>string.md</code> that overwrites its conceptual part which contains a <code>compare-strings</code> section. You can use one of the following syntax to link to this section:</p>
<pre><code class="lang-markdown">[compare strings](xref:System.String#compare-strings)

[compare strings](system.string.yml#compare-strings)
</code></pre>
<p>Both will render to:</p>
<pre><code class="lang-html">&lt;a href=&quot;system.string.html#compare-strings&quot;&gt;compare strings&lt;/a&gt;
</code></pre>
<h2 id="cross-reference-between-projects">Cross reference between projects</h2>
<p>Another common need is to reference topics from an external project. For example, when you're writing the documentation for your own .NET library, you'll want to add some links that point to types in .NET base class library. DocFX gives you two ways to achieve this functionality: by exporting all UIDs in a project into a map file to be imported in another project, and through cross reference services.</p>
<h3 id="cross-reference-map-file">Cross reference map file</h3>
<p>When building a DocFX project, there will be an <code>xrefmap.yml</code> generated under output folder. This file contains information for all topics that have UID defined and their corresponding urls. The format of <code>xrefmap.yml</code> looks like this:</p>
<pre><code class="lang-yaml">references:
- uid: uid_of_topic
  name: title_of_topic
  href: url_of_topic.html
  fullName: full_title_of_topic
- ...
</code></pre>
<p>It's a YAML object that contains following properties:</p>
<ol>
<li><code>references</code>: a list of topic information, each item contains following properties:
<ul>
<li><code>uid</code>: UID to a conceptual topic or API reference</li>
<li><code>name</code>: title of the topic</li>
<li><code>href</code>: url to the topic, which is an absolute url or relative path to current file (<code>xrefmap.yml</code>)</li>
<li><code>fullName</code>: doesn't apply to conceptual, means the fully qualified name of API. For example, for String class, its name is <code>String</code> and fully qualified name is <code>System.String</code>. This property is not used in link title resolve for now but reserved for future use.</li>
</ul>
</li>
</ol>
<div class="TIP">
<h5>Tip</h5>
<p>The topic is not necessarily a file, it can also be a section inside a file. For example, a method in a class.
In this case its url could be an anchor in a file.</p>
</div>
<h3 id="using-cross-reference-map">Using cross reference map</h3>
<p>Once you import a cross reference map file in your DocFX project, all UIDs defined in that file can be cross referenced.</p>
<p>To use a cross reference map, add a <code>xref</code> config to the <code>build</code> section of <code>docfx.json</code>:</p>
<pre><code class="lang-json">{
  &quot;build&quot;: {
    &quot;xref&quot;: [
      &quot;&lt;path_to_xrefmap&gt;&quot;
    ],
    ...
  }
}
</code></pre>
<p>The value of <code>xref</code> could be a string or a list of strings that contain the path/url to cross reference maps.</p>
<div class="NOTE">
<h5>Note</h5>
<p>DocFX supports reading cross reference map from a local file or a web location. It's recommended to deploy <code>xrefmap.yml</code> to
the website together with topic files so that others can directly use its url in <code>docfx.json</code> instead of downloading it to
local.</p>
</div>
<h3 id="cross-reference-services">Cross reference services</h3>
<p>Cross reference services are hosted services that can be queried for cross reference information. When DocFX generates the metadata for your project, it will perform cross reference lookups against the service.</p>
<p>To use a cross reference service, add a <code>xrefservice</code> config to the <code>build</code> section of <code>docfx.json</code>:</p>
<pre><code class="lang-json">{
  &quot;build&quot;: {
    &quot;xrefService&quot;: [ &quot;&lt;url_to_xrefservice&gt;&quot; ],
    ...
  }
}
</code></pre>
<p>For example, the URL for the cross reference service for .NET BCL types is <code>https://xref.docs.microsoft.com/query?uid={uid}</code>.</p>
<h2 id="advanced-more-options-for-cross-reference">Advanced: more options for cross reference</h2>
<p>You can create a cross link with following options:</p>
<ul>
<li><p><code>text</code>: the display text when the cross reference has been resolved correctly.</p>
<p>e.g.: <code>@&quot;System.String?text=string&quot;</code> will be resolved as <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.string">string</a>.</p>
</li>
<li><p><code>alt</code>: the display text when the cross reference does not have a <code>href</code> property.</p>
<p>e.g.: <code>&lt;xref href=&quot;System.Collections.Immutable.ImmutableArray`1?alt=ImmutableArray&quot;/&gt;</code> will be resolved as <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.collections.immutable.immutablearray-1">ImmutableArray&lt;T&gt;</a>.</p>
</li>
<li><p><code>displayProperty</code>: the property of display text when the cross reference is has resolved correctly.</p>
<p>e.g.: <code>&lt;a href=&quot;xref:System.String?displayProperty=fullName&quot;/&gt;</code> will be resolved as <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.string">System.String</a>.</p>
</li>
<li><p><code>altProperty</code>: the property of display text when the cross reference does not have a <code>href</code> property.</p>
<p>e.g.: <code>&lt;xref href=&quot;System.Collections.Immutable.ImmutableArray`1&quot; altProperty=&quot;name&quot;/&gt;</code> will be resolved as <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.collections.immutable.immutablearray-1">ImmutableArray&lt;T&gt;</a>.</p>
</li>
<li><p><code>title</code>: the title of link.</p>
<p>e.g.: <code>[](xref:System.String?title=String+Class)</code> will be resolved as <a class="xref" href="https://docs.microsoft.com/dotnet/api/system.string" title="String Class">String</a>.</p>
</li>
</ul>
<div id="disqus_thread"></div>
                <script>
                (function() { // DON'T EDIT BELOW THIS LINE
                var d = document, s = d.createElement('script');
                s.src = 'https://docfx-github.disqus.com/embed.js';
                s.setAttribute('data-timestamp', +new Date());
                (d.head || d.body).appendChild(s);
                })();
                </script>
                <noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
            </article>
          </div>
          
          <div class="hidden-sm col-md-2" role="complementary">
            <div class="sideaffix">
              <div class="contribution">
                <ul class="nav">
                  <li>
                    <a href="#disqus_thread" class="contribution-link">0 Comments</a>
                  </li>
                </ul>
              </div>
              <nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
              <!-- <p><a class="back-to-top" href="#top">Back to top</a><p> -->
              </nav>
            </div>
          </div>
        </div>
      </div>
      
      <footer>
        <div class="grad-bottom"></div>
        <div class="footer">
          <div class="container">
            <span class="pull-right">
              <a href="#top">Back to top</a>
            </span>
            <span>Copyright © 2015-2018 Microsoft<br>Generated by <strong>DocFX</strong></span>
            
          </div>
        </div>
      </footer>
    </div>
    
    <script type="text/javascript" src="../styles/docfx.vendor.js"></script>
    <script type="text/javascript" src="../styles/docfx.js"></script>
    <script type="text/javascript" src="../styles/main.js"></script>
    <script id="dsq-count-scr" src="//docfx-github.disqus.com/count.js" async=""></script>
    
    <script>
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
    
      ga('create', 'UA-99241001-1', 'auto');
      ga('send', 'pageview');
    
    </script>
  </body>
</html>
